==============================================================
  VULNERD — USER MANUAL
  Automated Security Report Card Engine
==============================================================
  Version: 1.0
  Last Updated: April 2026
==============================================================

TABLE OF CONTENTS
--------------------------------------------------------------
  1.  Introduction
  2.  System Requirements
  3.  Installation
  4.  Starting Vulnerd
        4a. Windows (Recommended)
        4b. Command Line (Windows)
        4c. Raspberry Pi / Linux Server
  5.  Preparing Your Nessus CSV File
  6.  Using the Web Interface
        6a. Uploading Your Scan File(s)
        6b. Selecting Business Type
        6c. Choosing Analysis Mode
        6d. Running the Analysis
  7.  Understanding Your Results
        7a. The Grade Card
        7b. Severity Breakdown Table
        7c. AI Analysis Sections
        7d. Compliance Dashboard
        7e. Trend Analysis View
  8.  Sending a PDF Report by Email
  9.  Using the Chat Feature
  10. Using the Command-Line Interface (CLI)
  11. Configuration & Settings
  12. Grading Reference
  13. Compliance Framework Reference
  14. Troubleshooting
  15. Frequently Asked Questions (FAQ)

==============================================================
1. INTRODUCTION
==============================================================
Vulnerd is a security report card tool that takes vulnerability
scan data from Nessus and turns it into a clear, easy-to-read
grade — just like a school report card.

Instead of staring at spreadsheets full of CVEs and technical
jargon, Vulnerd gives you:

  - A letter grade (A through F) for your network's security
  - A plain-English explanation of what the grade means
  - AI-generated analysis of your biggest risks
  - A compliance check against industry standards (HIPAA,
    PCI-DSS, NIST, FERPA, or CIS Controls)
  - A professional PDF report you can email to stakeholders
  - A chatbot you can ask questions about your results

Vulnerd is designed for IT administrators, small business
owners, compliance officers, and security teams who need to
communicate vulnerability findings clearly and quickly.

==============================================================
2. SYSTEM REQUIREMENTS
==============================================================
  Operating System:
    - Windows 10 / 11 (for desktop use)
    - Ubuntu 20.04+ or Raspberry Pi OS (for server use)

  Software:
    - Python 3.10 or higher
        Download: https://www.python.org/downloads/
        IMPORTANT: During installation, check the box that
        says "Add Python to PATH"

  Internet Connection:
    - Required for AI analysis (Google Gemini API)
    - Required for sending email reports

  Accounts / API Keys Needed:
    - Google Gemini API key (free)
        Sign up: https://aistudio.google.com
    - Gmail account with App Password enabled (for email)
        Setup: Google Account > Security > App Passwords

  Hardware:
    - Any modern PC or Raspberry Pi 3B+ or newer
    - Minimum 1 GB RAM recommended

==============================================================
3. INSTALLATION
==============================================================
Follow these steps the FIRST TIME you set up Vulnerd.

  STEP 1 — Install Python
    Download Python 3.10 or higher from:
      https://www.python.org/downloads/
    During installation, check "Add Python to PATH".

  STEP 2 — Install Required Packages
    Open Command Prompt in the Vulnerd folder and run:
      pip install -r requirements.txt

    This installs all necessary libraries including:
      - reportlab   (PDF generation)
      - google-generativeai  (Gemini AI)
      - python-dotenv  (configuration)
      - openai  (optional AI fallback)

  STEP 3 — Configure Your API Keys
    Open the file named ".env" in the Vulnerd folder
    (use Notepad or any text editor).

    Fill in your details:
      GEMINI_API_KEY=paste_your_key_here
      EMAIL_SENDER=your_gmail@gmail.com
      EMAIL_PASSWORD=your_gmail_app_password
      SMTP_SERVER=smtp.gmail.com
      SMTP_PORT=465

    Save and close the file.

    NOTE: To get a Gemini API key:
      1. Go to https://aistudio.google.com
      2. Sign in with a Google account
      3. Click "Get API Key" and copy it

    NOTE: To get a Gmail App Password:
      1. Go to your Google Account settings
      2. Navigate to Security > 2-Step Verification
      3. Scroll down to "App Passwords"
      4. Create a new app password for "Mail"
      5. Copy the 16-character password into .env

  STEP 4 — You're Ready!
    Proceed to Section 4 to start Vulnerd.

==============================================================
4. STARTING VULNERD
==============================================================

--------------------------------------------------------------
4a. WINDOWS (RECOMMENDED)
--------------------------------------------------------------
  1. Open the Vulnerd folder
  2. Double-click "Start Vulnerd.bat"
  3. A Command Prompt window will open (do not close it)
  4. Your default web browser will open automatically at:
       http://localhost:5001
  5. Vulnerd is now running and ready to use

  To stop Vulnerd: Close the Command Prompt window.

--------------------------------------------------------------
4b. COMMAND LINE (WINDOWS — MANUAL START)
--------------------------------------------------------------
  1. Open Command Prompt
  2. Navigate to the Vulnerd folder:
       cd C:\path\to\Vulnerd
  3. Run:
       python app.py
  4. Open your browser and go to:
       http://localhost:5001

--------------------------------------------------------------
4c. RASPBERRY PI / LINUX SERVER
--------------------------------------------------------------
  For full setup instructions, see: RASPBERRY_PI_SETUP.txt

  Quick start (once configured):
    python3 app.py

  If set up as a systemd service (auto-start on boot):
    sudo systemctl start vulnerd

  Access from any device on the same network:
    http://<raspberry-pi-ip-address>:5001

  To find your Pi's IP address:
    hostname -I

==============================================================
5. PREPARING YOUR NESSUS CSV FILE
==============================================================
Vulnerd reads vulnerability data exported from Nessus as a
CSV (comma-separated values) file.

  HOW TO EXPORT FROM NESSUS:
    1. Open Nessus and complete your vulnerability scan
    2. Open the completed scan results
    3. Click "Export" or "Download"
    4. Select format: CSV
    5. Save the file to your computer

  WHAT VULNERD READS FROM THE CSV:
    - Plugin ID and Name (vulnerability identifier)
    - Risk (Critical / High / Medium / Low / None)
    - Host / IP address
    - Protocol and Port
    - Description and Solution fields

  TIPS:
    - Make sure the export includes all severity levels
    - For Trend Analysis, export multiple scans separately
      and keep them clearly named (e.g., scan_jan.csv,
      scan_feb.csv) so you can track improvement over time
    - Vulnerd ignores rows with "None" risk (informational)

==============================================================
6. USING THE WEB INTERFACE
==============================================================

--------------------------------------------------------------
6a. UPLOADING YOUR SCAN FILE(S)
--------------------------------------------------------------
  On the main page you will see a large upload zone that says
  "Drop your Nessus CSV file here" or similar.

  TO UPLOAD:
    Option A — Drag and Drop:
      Drag your CSV file from File Explorer and drop it
      directly onto the upload zone.

    Option B — Click to Browse:
      Click anywhere in the upload zone to open a file
      browser, then select your CSV file.

  FOR TREND ANALYSIS (multiple files):
    Upload 2 or more CSV files. Each file should represent
    a different scan (e.g., from different months).
    Drop them all at once or one at a time.

  Once uploaded, the file name(s) will appear in the zone
  confirming the upload was successful.

--------------------------------------------------------------
6b. SELECTING BUSINESS TYPE
--------------------------------------------------------------
  Below the upload zone is a "Business Type" selector.
  Choose the option that best describes your organization:

    - Healthcare       (maps to HIPAA compliance)
    - Retail           (maps to PCI-DSS compliance)
    - Government       (maps to NIST 800-53 compliance)
    - Education        (maps to FERPA compliance)
    - General Business (maps to CIS Controls)

  This selection determines which compliance framework
  Vulnerd uses when evaluating your findings.

  If you are unsure, select "General Business."

--------------------------------------------------------------
6c. CHOOSING ANALYSIS MODE
--------------------------------------------------------------
  Select one of two analysis modes:

    SINGLE SCAN REPORT
      Use when you have one CSV file.
      Produces a full grade card, AI analysis, and
      compliance breakdown for a single point in time.

    TREND ANALYSIS
      Use when you have two or more CSV files.
      Compares scans over time, highlights improvement
      or regression, and shows progress patterns.

--------------------------------------------------------------
6d. RUNNING THE ANALYSIS
--------------------------------------------------------------
  1. Confirm your file is uploaded
  2. Select your business type
  3. Select your analysis mode
  4. Click the "Grade My Network" button

  Vulnerd will begin processing. A loading screen will
  appear with animated indicators and rotating motivational
  quotes. This typically takes 30–60 seconds depending on
  your internet speed and scan size.

  DO NOT close the browser or navigate away while the
  analysis is running.

  When complete, your results will appear automatically.

==============================================================
7. UNDERSTANDING YOUR RESULTS
==============================================================

--------------------------------------------------------------
7a. THE GRADE CARD
--------------------------------------------------------------
  The top of the results page shows your Grade Card:

    - LETTER GRADE: Large letter (A, B, C, D, or F)
      with +/- modifiers (e.g., B+, C-, D)

    - NUMERIC SCORE: Your score out of 100

    - GRADE COMMENTARY: A friendly explanation of what
      your grade means and the overall situation

  The grade is calculated by starting at 100 and subtracting
  points for each vulnerability found:
    Critical: -20 pts per finding
    High:      -8 pts per finding
    Medium:    -3 pts per finding
    Low:       -1 pt  per finding

--------------------------------------------------------------
7b. SEVERITY BREAKDOWN TABLE
--------------------------------------------------------------
  Below the grade card is a table showing the count of
  vulnerabilities by severity level:

    Severity    Count    Points Deducted
    ----------  -------  ---------------
    Critical    X        X * 20
    High        X        X * 8
    Medium      X        X * 3
    Low         X        X * 1

  This table helps you understand exactly what is driving
  your score down and where to prioritize remediation.

--------------------------------------------------------------
7c. AI ANALYSIS SECTIONS
--------------------------------------------------------------
  Vulnerd uses Google Gemini AI to generate detailed,
  plain-English analysis of your scan results. Each section
  is displayed as a collapsible card. Click any section
  header to expand or collapse it.

  SINGLE SCAN — Sections Included:

    Executive Summary
      A high-level overview of your security posture
      written for non-technical stakeholders. Suitable
      for sharing with management or board members.

    Key Findings
      The most significant vulnerabilities identified,
      explained in plain language with context about
      why they matter.

    Contributing Factors
      Root causes and patterns behind your vulnerabilities.
      Helps identify systemic issues rather than
      individual problems.

    Recommendations
      Specific, prioritized action items to improve
      your security grade. Ordered by impact.

    Threat Context
      Real-world context for your vulnerabilities —
      what types of attackers exploit them and how.

    Who to Call
      Guidance on which internal teams or external
      resources to engage based on your findings.

    Instructor's Note
      An encouraging summary styled like a teacher's
      note on a report card. Honest but motivating.

  TREND ANALYSIS — Sections Included:

    Progress Summary
      Overall view of how your security posture has
      changed across all uploaded scans.

    Scan-by-Scan Review
      Individual breakdown of each scan with grade
      and notable changes from the previous period.

    Patterns to Address
      Recurring vulnerabilities or problem areas that
      have persisted across multiple scans.

    Areas of Improvement
      Vulnerabilities that have been resolved or
      reduced — celebrating progress made.

    Recommended Next Steps
      Prioritized action plan based on trends observed
      across your scan history.

    Threat Context
      How your current exposure compares to evolving
      threat landscapes.

    Who to Call
      Resource guidance based on your trend patterns.

    Progress Report Comment
      Teacher-style summary of your improvement journey.

--------------------------------------------------------------
7d. COMPLIANCE DASHBOARD
--------------------------------------------------------------
  On the right side of the results page (or below on
  smaller screens) is the Compliance Dashboard.

  This panel shows how your scan results relate to your
  selected compliance framework. For each framework
  attribute, you will see:

    - Attribute Name (e.g., "Access Controls" for HIPAA)
    - Risk Score (how exposed you are in this area)
    - Real-World Impact (what could go wrong)
    - Cost Estimate (potential breach cost vs. fix cost)

  Use this section when preparing for audits or when
  explaining security risks in business terms.

--------------------------------------------------------------
7e. TREND ANALYSIS VIEW
--------------------------------------------------------------
  When using Trend Analysis mode, a history table appears
  showing all uploaded scans with:

    - Scan date / file name
    - Letter grade
    - Numeric score
    - Vulnerability counts by severity
    - Change from previous scan (+/- indicators)

  A positive trend (score going up, fewer criticals) means
  your remediation efforts are working.

==============================================================
8. SENDING A PDF REPORT BY EMAIL
==============================================================
Vulnerd can generate a professional PDF report card and
email it directly to any recipient.

  HOW TO SEND A REPORT:
    1. After your analysis completes, scroll to the
       "Send Report" section
    2. Enter the recipient's email address
    3. Click "Send Report"
    4. A confirmation message will appear when the
       email has been sent successfully

  WHAT THE PDF INCLUDES:
    - Grade badge with letter and score
    - Severity breakdown table
    - All AI-generated analysis sections
    - Compliance framework summary
    - Report metadata (date generated, scan hash)
    - Vulnerd branding and footer

  EMAIL SUBJECT FORMAT:
    "Vulnerd Security Report Card — Grade [X] | [Date]"

  NOTE: You must have EMAIL_SENDER and EMAIL_PASSWORD
  configured in your .env file for this to work.
  See Section 3 (Installation) or Section 11 (Configuration).

==============================================================
9. USING THE CHAT FEATURE
==============================================================
Vulnerd includes an AI-powered chatbot that lets you ask
questions about your scan results in plain English.

  HOW TO ACCESS THE CHAT:
    After running an analysis, look for the chat button
    in the bottom-right corner of the screen (it looks
    like a speech bubble or chat icon).
    Click it to open the chat panel.

  WHAT YOU CAN ASK:
    - "What is my most critical vulnerability?"
    - "Which hosts have the most problems?"
    - "What should I fix first?"
    - "What does a Critical finding mean?"
    - "How do I fix the vulnerabilities on port 443?"
    - "Is my score good enough for PCI compliance?"
    - "Explain my executive summary in simpler terms."

  HOW IT WORKS:
    The chatbot uses Google Gemini AI with full context
    of your scan results. Every answer is grounded in
    your specific data — not generic security advice.

  TIPS:
    - Be specific in your questions for better answers
    - You can ask follow-up questions in the same session
    - The chat context resets if you run a new analysis

==============================================================
10. USING THE COMMAND-LINE INTERFACE (CLI)
==============================================================
The CLI version (vulnerd.py) is designed for users who
prefer terminal-based workflows, headless servers, or
automated reporting pipelines.

  SETUP:
    Place your Nessus CSV file(s) in the folder:
      ./evidence_locker/
    (Create this folder if it does not exist)

  RUNNING THE CLI:
    Open a terminal in the Vulnerd folder and run:
      python vulnerd.py    (Windows)
      python3 vulnerd.py   (Linux / Raspberry Pi)

  INTERACTIVE MENU:
    The CLI will present you with options:

      [1] Single Report
          Analyzes one CSV file and emails the report.
          You will be prompted to:
            - Select the CSV file from the evidence_locker
            - Enter a recipient email address
          Vulnerd generates the PDF and sends it.

      [2] Trend Analysis
          Analyzes multiple CSV files and compares them.
          You will be prompted to:
            - Select which CSV files to include
            - Enter a recipient email address
          Vulnerd generates a trend report and sends it.

  OUTPUT:
    Generated PDF reports are saved to: ./reports/
    Each PDF is named with the date and analysis type.

  USE CASES FOR CLI:
    - Scheduled/automated scans (cron jobs)
    - Raspberry Pi deployments without a monitor
    - Batch processing multiple scans
    - Environments where a browser is not available

==============================================================
11. CONFIGURATION & SETTINGS
==============================================================
All configuration is stored in the ".env" file located in
the main Vulnerd folder. Open it with any text editor.

  SETTING            DESCRIPTION
  -----------------  ----------------------------------------
  GEMINI_API_KEY     Your Google Gemini API key (required)
                     Get one at: https://aistudio.google.com

  OPENAI_API_KEY     OpenAI API key (optional)
                     Used as fallback if Gemini is unavailable

  EMAIL_SENDER       Your Gmail address used to send reports

  EMAIL_PASSWORD     Your Gmail App Password (NOT your regular
                     Gmail password — must be an App Password)

  SMTP_SERVER        Email server (default: smtp.gmail.com)

  SMTP_PORT          Email port (default: 465)

  AI MODEL FALLBACK CHAIN:
  If the primary AI model is unavailable, Vulnerd
  automatically tries the next in this order:
    1. Google Gemini 2.5-flash        (primary)
    2. Google Gemini 2.5-flash-lite   (fallback 1)
    3. OpenAI GPT-4o-mini             (fallback 2)
    4. OpenAI GPT-3.5-turbo           (fallback 3)

  SERVER PORT:
  Vulnerd runs on port 5001 by default. To change this,
  edit the last line of app.py where the server starts.

==============================================================
12. GRADING REFERENCE
==============================================================
  Score    Grade   Commentary Summary
  -------  ------  -----------------------------------------
  93-100    A      Excellent — strong, well-managed posture
  90-92     A-     Really strong results, minor improvements
  87-89     B+     Good, above average performance
  83-86     B      Solid foundation with clear next steps
  80-82     B-     Passing, improvement path is clear
  77-79     C+     Real work to do, prioritize high/criticals
  73-76     C      Meaningful exposure, prompt attention needed
  70-72     C-     Critical and High items are urgent
  67-69     D+     High-priority items need immediate action
  63-66     D      Urgent remediation required now
  60-62     D-     Immediate escalation recommended
  0-59       F     Serious exposure — escalate today

  SCORING FORMULA:
    Start:          100 points
    Per Critical:    -20 points
    Per High:         -8 points
    Per Medium:       -3 points
    Per Low:          -1 point
    Minimum score:     0 (cannot go below zero)

==============================================================
13. COMPLIANCE FRAMEWORK REFERENCE
==============================================================

  HIPAA (Healthcare)
    Health Insurance Portability and Accountability Act.
    Protects patient health information (PHI).
    Key areas: Access Controls, Audit Controls, Integrity,
    Transmission Security, Device Security.

  PCI-DSS (Retail / Payments)
    Payment Card Industry Data Security Standard.
    Protects cardholder data.
    Key areas: Network Security, Access Management, Encryption,
    Vulnerability Management, Monitoring.

  NIST 800-53 (Government)
    National Institute of Standards and Technology controls.
    Federal information system security standards.
    Key areas: Identification, Authentication, Incident Response,
    System Integrity, Configuration Management.

  FERPA (Education)
    Family Educational Rights and Privacy Act.
    Protects student education records.
    Key areas: Data Access, Record Integrity, Disclosure Controls,
    System Security, Audit Trails.

  CIS Controls (General Business)
    Center for Internet Security Critical Security Controls.
    Practical, prioritized security best practices.
    Key areas: Inventory Management, Vulnerability Management,
    Controlled Access, Audit Logging, Incident Response.

==============================================================
14. TROUBLESHOOTING
==============================================================

  PROBLEM: Python not found / "python is not recognized"
  SOLUTION:
    - Install Python 3.10+ from https://python.org
    - During installation, check "Add Python to PATH"
    - Restart Command Prompt after installing
    - Try "python3" instead of "python" on some systems

  PROBLEM: "Module not found" or import errors
  SOLUTION:
    - Run: pip install -r requirements.txt
    - If pip fails: python -m pip install -r requirements.txt
    - Make sure you are in the Vulnerd folder when running

  PROBLEM: Browser does not open automatically
  SOLUTION:
    - Manually open your browser
    - Go to: http://localhost:5001
    - Make sure the Command Prompt window is still open

  PROBLEM: "Connection refused" in browser
  SOLUTION:
    - Make sure app.py is still running (check Command Prompt)
    - Try refreshing the page
    - Confirm port 5001 is not blocked by firewall

  PROBLEM: AI analysis not generating / blank sections
  SOLUTION:
    - Verify GEMINI_API_KEY is correctly set in .env
    - Check your internet connection
    - The free Gemini API tier has usage limits —
      wait a few minutes and try again
    - Ensure your .env file is saved and in the correct folder

  PROBLEM: Email not sending
  SOLUTION:
    - Use a Gmail App Password (not your regular password)
    - Enable 2-Step Verification on your Google account first
    - Confirm EMAIL_SENDER and EMAIL_PASSWORD in .env are correct
    - Check that SMTP_SERVER=smtp.gmail.com and SMTP_PORT=465

  PROBLEM: CSV file not accepted / parsing error
  SOLUTION:
    - Make sure your CSV was exported directly from Nessus
    - Do not modify the CSV file before uploading
    - Ensure the file extension is .csv (not .xlsx or .txt)
    - Try re-exporting from Nessus

  PROBLEM: Analysis takes very long or times out
  SOLUTION:
    - Large CSV files with many findings take longer
    - Check your internet connection speed
    - The Gemini API may be experiencing high load —
      try again after a few minutes

  PROBLEM: Grade seems unexpectedly low
  SOLUTION:
    - Check the severity breakdown table for high counts
    - Remember: each Critical finding deducts 20 points
    - The score floor is 0 — many criticals can stack up
    - This is by design to reflect real security risk

==============================================================
15. FREQUENTLY ASKED QUESTIONS (FAQ)
==============================================================

  Q: Does Vulnerd store my scan data anywhere?
  A: No. Vulnerd is stateless. Your scan data is processed
     in memory and discarded when you close the browser or
     restart the server. PDFs are temporarily cached in
     memory for email delivery only.

  Q: Can I use Vulnerd with scanners other than Nessus?
  A: Vulnerd is designed for Nessus CSV exports. Other
     scanners may work if their CSV format matches Nessus
     (columns: Plugin ID, Risk, Host, Protocol, Port, Name,
     Description, Solution), but this is not guaranteed.

  Q: How many scans can I upload for trend analysis?
  A: There is no hard limit. Uploading 3–12 scans gives the
     best trend analysis results. Very large numbers of files
     may increase processing time.

  Q: Is my API key safe?
  A: Your API key is stored locally in your .env file and
     is never transmitted anywhere except to Google's Gemini
     API servers for analysis. Keep your .env file private
     and never share it publicly.

  Q: Can multiple people use Vulnerd at the same time?
  A: Yes, if Vulnerd is running on a shared server
     (like a Raspberry Pi), multiple users on the same
     network can access it simultaneously via their browsers.

  Q: What happens if Gemini is unavailable?
  A: Vulnerd automatically falls back through a chain of
     AI models (see Section 11). If all models fail, an
     error message will appear and you can try again.

  Q: Can I run Vulnerd without an internet connection?
  A: The grading and CSV parsing work offline, but the
     AI analysis sections require an internet connection
     to reach the Gemini API.

  Q: How do I update Vulnerd?
  A: Replace the project files with the new version.
     Your .env configuration file will be preserved as long
     as you do not overwrite it.

  Q: Who made Vulnerd?
  A: Vulnerd was developed as a capstone project to make
     vulnerability management more accessible to organizations
     that lack dedicated security teams.

==============================================================
  END OF USER MANUAL
==============================================================
